home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 16 / AMIGAplus Sonderheft 16 (1998)(ICP)(DE)[!].iso / pd / anwendungen / xpk_develop / autodocs / xpkmaster.doc next >
Text File  |  1998-08-27  |  32KB  |  846 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/--general--
  4. xpkmaster.library/XpkAllocObject
  5. xpkmaster.library/XpkClose
  6. xpkmaster.library/XpkExamine
  7. xpkmaster.library/XpkFault
  8. xpkmaster.library/XpkFreeObject
  9. xpkmaster.library/XpkOpen
  10. xpkmaster.library/XpkPack
  11. xpkmaster.library/XpkPassRequest
  12. xpkmaster.library/XpkPrintFault
  13. xpkmaster.library/XpkQuery
  14. xpkmaster.library/XpkRead
  15. xpkmaster.library/XpkUnpack
  16. xpkmaster.library/XpkWrite
  17. xpkmaster.library/--tags--
  18. xpkmaster.library/--progress--
  19. xpkmaster.library/--data hooks--
  20.  
  21. xpkmaster.library/--general--                   xpkmaster.library/--general--
  22.  
  23.     xpkmaster.library is designed to work under minimum systems. So you may
  24.     use it in games with disabled multitasking as well. It needs access to
  25.     system libraries: utilities.library, exec.library, gadtools.library,
  26.     intuition.library and dos.library. XPK supports locale.library to
  27.     localize internal strings. When locale.library is installed, the first
  28.     access to this library causes an access to ENV: assign, so this assign
  29.     must exist when locale.library is installed.
  30.  
  31. xpkmaster.library/XpkAllocObject             xpkmaster.library/XpkAllocObject
  32.  
  33.     NAME
  34.         XpkAllocObject - Allocate memory for xpk related structures (V4)
  35.  
  36.     SYNOPSIS
  37.         ptr = XpkAllocObject(type, tags)
  38.         D0                    D0    A0
  39.  
  40.         APTR  XpkAllocObject(ULONG , struct TagItem *)
  41.  
  42.         ptr = XpkAllocObjectTags(type, firsttag, ...)
  43.  
  44.         APTR  XpkAllocObjectTags(ULONG, Tag, ...)
  45.  
  46.     FUNCTION
  47.         This function allocates the memory of a needed xpk related
  48.         structure and initializes it. It should help to bring better
  49.         upwards compatibility in next versions. Use it always in newer code.
  50.  
  51.     INPUT
  52.         type    - in xpk/xpk.h defined XPKOBJ_... types.
  53.                   for example XPKOBJ_FIB alloctes XpkFib structure
  54.         tags    - Pointer to an array of struct TagItem. No tags defined
  55.                   at the moment.
  56.  
  57.     RESULT
  58.         ptr     - Pointer to allocated memory of needed size or 0 when an
  59.                   error occured.
  60.  
  61.     SEE ALSO
  62.         xpk/xpk.h, XpkFreeObject()
  63.  
  64. xpkmaster.library/XpkClose                         xpkmaster.library/XpkClose
  65.  
  66.     NAME
  67.         XpkClose - Close an XPK-File
  68.  
  69.     SYNOPSIS
  70.         err = XpkClose(xfh)
  71.         D0              A0
  72.  
  73.         LONG  XpkClose(struct XpkFib *)
  74.  
  75.     FUNCTION
  76.         Frees all resources associated with packing or unpacking an
  77.         XPK-File. Note that this may well fail, especially on packing,
  78.         since additional writes have to be made here.
  79.  
  80.     INPUT
  81.         xfh     - The Struct XpkFib obtained from XpkOpen()
  82.  
  83.     RESULT
  84.         err     - Global Xpk error code
  85.  
  86.     SEE ALSO
  87.         XpkOpen(), XpkRead(), XpkWrite()
  88.  
  89. xpkmaster.library/XpkExamine                     xpkmaster.library/XpkExamine
  90.  
  91.     NAME
  92.         XpkExamine - Get information about a compressed file
  93.  
  94.     SYNOPSIS
  95.         err = XpkExamine(fib, tags)
  96.         D0                A0   A1
  97.  
  98.         LONG  XpkExamine(struct XpkFib *, struct TagItem *)
  99.  
  100.         err = XpkExamineTags(fib, firsttag, ...)
  101.  
  102.         LONG  XpkExamineTags(struct XpkFib *, Tag, ...)
  103.  
  104.     FUNCTION
  105.         Returns information about compressed data. The output is written
  106.         to the XpkFib structure whose address is passed with the mandatory
  107.         XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note
  108.         that the file position of the in hook will not be altered.
  109.     XPK_GetError is supported.
  110.         A tag field has to end with TAG_DONE.
  111.  
  112.     INPUT
  113.         tags    - Pointer to an array of struct TagItem. You may use 
  114.                   either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook
  115.                   tag.
  116.  
  117.     RESULT
  118.         err     - Global Xpk error code
  119.  
  120.     SEE ALSO
  121.         xpk/xpk.h
  122.  
  123. xpkmaster.library/XpkFault                         xpkmaster.library/XpkFault
  124.  
  125.     NAME
  126.         XpkFault - Returns the text associated with a Xpk error code (V4)
  127.  
  128.     SYNOPSIS
  129.         len = XpkFault(code, header, buffer, bufsize)
  130.         D0              D0     A0      A1     D1
  131.  
  132.         LONG XpkFault(LONG, STRPTR, STRPTR, LONG)
  133.  
  134.     FUNCTION
  135.         This routine obtains the error message text for the given error code.
  136.         The header is prepended to the text of the error message, followed
  137.         by a colon. Puts a null-terminated string for the error message into
  138.         the buffer. At most len bytes are written to buffer.
  139.  
  140.     INPUTS
  141.         code    - Error code (negative value or 0)
  142.         header  - header to output before error text
  143.         buffer  - Buffer to receive error message.
  144.         bufsize - Length of the buffer.
  145.  
  146.     RESULT
  147.         len     - number of characters put into buffer (may be 0)
  148.  
  149.     SEE ALSO
  150.         XpkPrintFault()
  151.  
  152. xpkmaster.library/XpkFreeObject               xpkmaster.library/XpkFreeObject
  153.  
  154.     NAME
  155.         XpkFreeObject - Frees memory allocated with XpkAllocObject() (V4)
  156.  
  157.     SYNOPSIS
  158.         XpkFreeObject(type, object)
  159.                        D0     A0
  160.  
  161.         void XpkFreeObject(ULONG , APTR)
  162.  
  163.     FUNCTION
  164.         Frees object allocated by XpkAllocObject(). Do not call for objects
  165.         allocated in any other way.
  166.  
  167.     INPUTS
  168.         type    - type passed to XpkAllocObject()
  169.         object  - pointer returned by XpkAllocObject()
  170.  
  171.     SEE ALSO
  172.         xpk/xpk.h, XpkAllocObject()
  173.  
  174. xpkmaster.library/XpkOpen                           xpkmaster.library/XpkOpen
  175.  
  176.     NAME
  177.         XpkOpen - Open a compressed file for partial reading
  178.  
  179.     SYNOPSIS
  180.         err = XpkOpen(xfh, tags)
  181.         D0            A0    A1
  182.  
  183.         LONG  XpkOpen(struct XpkFib **, struct TagItem *)
  184.  
  185.     FUNCTION
  186.         Using XpkOpen you can read or write an XPK file without ever having
  187.         all of the file present in RAM. On reading, you cannot pick the 
  188.         size of the chunks. They are given by the file to be decompressed
  189.         and may be up to the whole size of the file.
  190.     XPK_GetError is supported.
  191.  
  192.     INPUT
  193.         xfh     - Address of a pointer to struct XpkFib
  194.         tags    - Specifying XPK_PackMethod will chose packing mode for
  195.                   this filehandle. Only In-tags are permitted in case
  196.                   of unpacking, and only Out-tags are in case of packing.
  197.                   Anything else will yield undefined results. Progress
  198.                   reports not supported. When packing, you must supply
  199.                   XPK_InLen as well.
  200.  
  201.     RESULT
  202.         xfh     - The filehandle. Consists of an XpkFib and some private
  203.                   information. The NLen field in the XpkFib indicates the
  204.                   length of the next chunk.
  205.         err     - Global Xpk error code. If nonzero, no XpkFib was allocated.
  206.  
  207.     SEE ALSO
  208.         XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/--tags--
  209.  
  210. xpkmaster.library/XpkPack                           xpkmaster.library/XpkPack
  211.  
  212.     NAME
  213.         XpkPack - Compress a data stream
  214.  
  215.     SYNOPSIS
  216.         err = XpkPack(tags)
  217.         D0             A0
  218.  
  219.         LONG  XpkPack(struct TagItem *)
  220.  
  221.         err = XpkPackTags(firsttag, ...)
  222.  
  223.         LONG  XpkPackTags(Tag, ...)
  224.  
  225.     FUNCTION
  226.         Compresses a file or a memory area to a different file or memory
  227.         area. You need to specify at least one XPK_In... tag, at least
  228.         one XPK_Out... tag, plus XPK_PackMethod.
  229.     XPK_GetError is supported.
  230.         A tag field has to end with TAG_DONE.
  231.  
  232.     INPUT
  233.         tags    - Pointer to an array of struct TagItem.
  234.  
  235.     RESULT
  236.         err     - Global Xpk error code.
  237.  
  238.     SEE ALSO
  239.         xpkmaster.library/--tags--, xpk/xpk.h
  240.  
  241. xpkmaster.library/XpkPassRequest             xpkmaster.library/XpkPassRequest
  242.  
  243.     NAME
  244.         XpkPassRequest - opens a password Requester (V4)
  245.  
  246.     SYNOPSIS
  247.         err = XpkPassRequest(tags)
  248.         D0                    A0
  249.  
  250.         LONG  XpkPassRequest(struct TagItem *)
  251.  
  252.         err = XpkPassRequestTags(firsttag, ...)
  253.  
  254.         LONG  XpkPassRequestTags(Tag, ...)
  255.  
  256.     FUNCTION
  257.         Opens a requester to ask the user for a password. The requester
  258.         can ask for a password or a 16/32 bit key. It has a tunable
  259.         timeout to allow batch work.
  260.  
  261.     This function needs at least 2 free signal bits for message ports.
  262.  
  263.     INPUT
  264.         tags    - Pointer to an array of struct TagItem.
  265.                   Either XPK_Preferences or one of the following:
  266.  
  267.     TAGS
  268.         XPK_PassChars   (ULONG)
  269.            Tell the requester which characters are allowed in the password.
  270.            Use XPKPASSFLG_... and XPKPASSFF_... defines.
  271.  
  272.         XPK_PasswordBuf (STRPTR)
  273.            Pointer to memory area, where the password should be stored.
  274.            Requires XPK_PassBuffSize tag.
  275.  
  276.         XPK_PassBufSize (ULONG)
  277.            Size of the buffer passed with XPK_PasswordBuf.
  278.  
  279.         XPK_Key16BitPtr (UWORD *)
  280.            Ask for an 16 bit key instead of a password. Data is a pointer
  281.            to a 16 bit (UWORD) variable. XPK_PassChars is ignored here, as
  282.            input is always hexadecimal.
  283.  
  284.         XPK_Key32BitPtr (ULONG *)
  285.            Ask for an 32 bit key. Data points to a 32 bit (ULONG) variable.
  286.        XPK_PassChars is ignored here, as input is always hexadecimal.
  287.  
  288.         XPK_PubScreen (struct Screen *)
  289.            Pointer of type struct Screen of the public screen, the
  290.            requester should open on. If not given, the requester opens on
  291.            default public screen. The screen must by locked by use of
  292.            LockPubScreen or garanted not to be closed during request!
  293.  
  294.         XPK_PassTitle (STRPTR)
  295.            Is the text, which is shown in the title line of the window. If
  296.            not given, the internal defaults are used.
  297.  
  298.         XPK_TimeOut (ULONG)
  299.            Time after which the requester should close automatically, when
  300.            no user action happend. 0 means no timeout.
  301.  
  302.     XPK_PassVerify (BOOL) (V4 REV25)
  303.        When this tag is specified, the user needs to enter the password
  304.        or passkey twice for verification. This option should be used
  305.        when password is needed for packing.
  306.  
  307.     XPK_PassWinLeft (UWORD) (V4 REV25)
  308.        This specifies the distance from left screen border to left
  309.        border of password requester. When not given, the window is
  310.        centered on screen.
  311.  
  312.     XPK_PassWinTop (UWORD) (V4 REV25)
  313.        This specifies the distance from top screen border to top
  314.        border of password requester. When not given, the window is
  315.        centered on screen.
  316.  
  317.     XPK_PassWinWidth (UWORD) (V4 REV25)
  318.        This specifies the width of the password requester. It must be
  319.        large enough (50 + borders) or the internal defaults are used.
  320.  
  321.     XPK_PassWinHeight (UWORD) (V4 REV25)
  322.        This specifies the height of the password requester. It must be
  323.        large enough (inner height a bit larger than font height) or the
  324.        internal defaults are used.
  325.  
  326.     XPK_PassCenter (BOOL) (V4 REV25)
  327.        When this is given, the above XPK_PassWinLeft and XPK_PassWinTop
  328.        are are interpreted as the center of the requester and not as
  329.        its upper left edge.
  330.  
  331.     RESULT
  332.         err     - Global Xpk error code.
  333.  
  334.     SEE ALSO
  335.         xpk/xpk.h
  336.  
  337. xpkmaster.library/XpkPrintFault               xpkmaster.library/XpkPrintFault
  338.  
  339.     NAME
  340.         XpkPrintFault - Prints the text associated with a Xpk error code (V4)
  341.  
  342.     SYNOPSIS
  343.         success = XpkPrintFault(code, header)
  344.         D0                       D0     A0
  345.  
  346.         BOOL XpkPrintFault(LONG, STRPTR)
  347.  
  348.     FUNCTION
  349.         This routine obtains and prints the error message text for the
  350.         given error code. This is similar to the XpkFault() function,
  351.         except that the output is written to the default output
  352.         channel with buffered output.
  353.  
  354.     INPUTS
  355.         code    - Error code (negative value or 0)
  356.         header  - header to output before error text
  357.  
  358.     RESULT
  359.         success - Success/failure code. Return of 0 means failure.
  360.  
  361.     SEE ALSO
  362.         XpkFault()
  363.  
  364. xpkmaster.library/XpkQuery                         xpkmaster.library/XpkQuery
  365.  
  366.     NAME
  367.         XpkQuery - Gain information about packers
  368.  
  369.     SYNOPSIS
  370.         err = XpkQuery(tags)
  371.         D0              A0
  372.  
  373.         LONG  XpkQuery(struct TagItem *)
  374.  
  375.         err = XpkQueryTags(firsttag, ...)
  376.  
  377.         LONG  XpkQueryTags(Tag, ... )
  378.  
  379.     FUNCTION
  380.         Finds out a list of available packers or various parameters of a
  381.         packer. When using the tag XPK_PackersQuery, you must supply a
  382.         XpkPackerList structure and will receive a list of available
  383.         packers. The second possibility, XPK_PackerQuery, expects a
  384.         pointer to a XpkPackerInfo structure which will be filled in with
  385.         information about a packer, and XPK_ModeQuery fills in a XpkMode
  386.         structure with information about some mode (or the default mode)
  387.         of a packer. XPK_PackMethod must be present when using the latter
  388.         two queries, and XPK_PackMode can be for ModeQuery.
  389.     XPK_GetError is supported. Every call only one query is allowed!
  390.  
  391.     The flag XPKIF_MODES does not mean, the library supports different
  392.     mode settings (as ALL libraries do that), but means there are
  393.     different XpkMode structures! So when XPKIF_MODES is not set, the
  394.     user still needs to be able to select all 100 modes!
  395.  
  396.     Pass {XPK_Preferences, FALSE} as tags to disable the dummy packer
  397.     USER, which implements the preferences packing. Then handle the
  398.     preferences mode internally, as the statistics passed with
  399.     XPK_ModeQuery and XPK_PackerQuery are not very useful.
  400.  
  401.     RESULT
  402.         err     - Global Xpk error code.
  403.  
  404.     SEE ALSO
  405.         xpk/xpk.h
  406.  
  407. xpkmaster.library/XpkRead                           xpkmaster.library/XpkRead
  408.  
  409.     NAME
  410.         XpkRead - Unpack one part of an XPK-File
  411.  
  412.     SYNOPSIS
  413.         read = XpkRead( xfh, buf, len )
  414.         D0              A0   A1   D0
  415.  
  416.         LONG  XpkRead(struct XpkFib *, UBYTE *, LONG)
  417.  
  418.     FUNCTION
  419.         Reads one chunk from an XPK-file and decompresses it to the
  420.         memory area indicated.
  421.  
  422.     INPUT
  423.         xfh     - The XpkFib obtained from XpkOpen(). It must be a read-
  424.                   handle, ie. there was no XPK_PackMethod tag among the
  425.                   tags passed to XpkOpen().
  426.         buf     - The memory area to write the destination to
  427.         len     - The number uncompressed bytes to output. Note that you
  428.                   cannot choose these freely but must take them from 
  429.                   the xf_NLen field in the XpkFib.
  430.  
  431.     RESULT
  432.         read    - The number of bytes read. 0 indicates EOF, negative
  433.                   numbers are global error codes. Long error messages 
  434.                   written to buffer passed through XPK_GetError in 
  435.                   XpkOpen(). This number of bytes read will usually be
  436.                   smaller than the number requested!
  437.  
  438.     SEE ALSO
  439.         XpkOpen(), XpkWrite(), XpkClose(), examples/
  440.  
  441. xpkmaster.library/XpkUnpack                       xpkmaster.library/XpkUnpack
  442.  
  443.     NAME
  444.         XpkUnpack - Decompress a data stream
  445.  
  446.     SYNOPSIS
  447.         err = XpkUnpack(tags)
  448.         D0             A0
  449.  
  450.         LONG  XpkUnpack(struct TagItem *)
  451.  
  452.         err = XpkUnpackTags(firsttag, ...)
  453.  
  454.         LONG  XpkUnpackTags(Tag, ...)
  455.  
  456.     FUNCTION
  457.         Decompresses a file or a memory area to a different file or memory
  458.         area. You need to specify at least one XPK_In... tag, at least
  459.         one XPK_Out... tag. A tag field has to end with TAG_DONE.
  460.     XPK_GetError is supported.
  461.  
  462.     INPUT
  463.         tags   - Pointer to an array of struct TagItem.
  464.  
  465.     RESULT
  466.         err    - Global Xpk error code.
  467.  
  468.     SEE ALSO
  469.         xpkmaster.library/--tags--
  470.  
  471. xpkmaster.library/XpkWrite                         xpkmaster.library/XpkWrite
  472.  
  473.     NAME
  474.         XpkWrite - Pack one part of an XPK-File
  475.  
  476.     SYNOPSIS
  477.         err = XpkWrite(xfh, buf, len)
  478.         D0              A0   A1   D0
  479.  
  480.         LONG  XpkWrite(struct XpkFib *, UBYTE *, LONG)
  481.  
  482.     FUNCTION
  483.         Compresses the memory area indicated and writes it to an
  484.         XPK-File.
  485.  
  486.     INPUT
  487.         xfh     - The XpkFib obtained from XpkOpen(). Must be a write-
  488.                   handle, ie. XPK_PackMethod must have been among the
  489.                   tags passed to XpkOpen().
  490.         buf     - The memory area to compress
  491.         len     - The number bytes to compress. Note you may not choose
  492.                   them freely, you must always deliver as many bytes
  493.                   as the NLen field of the XpkFib indicates. You may try
  494.                   to influence it by passing XPK_ChunkLen to XpkOpen().
  495.                   Important: The first chunk written *must* be the
  496.                   biggest!
  497.  
  498.     RESULT
  499.         err    - global error codes. Error messages are written to
  500.               buffer passed through XPK_GetError in XpkOpen().
  501.  
  502.     SEE ALSO
  503.         XpkOpen(), XpkRead(), XpkClose(), examples/
  504.  
  505. xpkmaster.library/--tags--                         xpkmaster.library/--tags--
  506.  
  507.     THE TAGS FOR XpkPack() AND XpkUnpack()
  508.  
  509.     THE INPUT TAGS. One of the four must be present.
  510.  
  511.         XPK_InName (STRPTR)
  512.             Name of file to (de)compress. On packing, XPK_InLen can be 
  513.             specified in order to pack only the first N bytes. On de-
  514.             compression, only one file will be decompressed, even if 
  515.             there is additional data at the end.
  516.  
  517.         XPK_InFH (BPTR)
  518.             File handle to (de)compress from. It is not necessary that
  519.             the handle is at the beginning of the file. Otherwise same
  520.             rules as in XPK_InName apply.
  521.  
  522.         XPK_InBuf (STRPTR)
  523.             Memory block to (de)compress. If you use this one, you 
  524.             have to specify InLen as well.
  525.  
  526.         XPK_InHook (struct Hook *)
  527.             Hookfunc to deliver data for (de)compression. See special
  528.             chapter on I/O hook functions. Must also supply XPK_InLen,
  529.             else the hook itself is asked for input filelength.
  530.  
  531.     IN ADDITION
  532.  
  533.         XPK_InLen (LONG)
  534.             Specifies the number of bytes to read when compressing.
  535.             ignored on decompression of normal xpk files. It should be
  536.             supplied for decompression to allow decrunching of non xpk
  537.             files.
  538.  
  539.     THE OUTPUT TAGS. One of the five must be present.
  540.  
  541.         XPK_OutName (STRPTR)
  542.             Name of file write (de)compressed data to.
  543.  
  544.         XPK_OutFH (BPTR)
  545.             File handle to append (de)compressed data to. This filehandle
  546.             must be writable, so MODE_OLDFILE filehandles may fail, as
  547.             these open a file in shared mode.
  548.  
  549.         XPK_OutBuf (APTR)
  550.             The memory block to write (de)compressed data to. Must also
  551.             supply XPK_OutBufLen. On packing, its size must be at least
  552.             inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be
  553.             outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note
  554.             that this buffer must be word aligned.
  555.  
  556.         XPK_GetOutBuf (APTR *)
  557.             Allocates a block of appropriate size and stores a pointer to
  558.             it in the variable pointed to by ti_Data. Must also supply 
  559.             XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType.
  560.  
  561.         XPK_OutHook (struct Hook *)
  562.             Hookfunc to accept (de)compressed data. See special chapter
  563.             on I/O hook functions.
  564.  
  565.     IN ADDITION
  566.  
  567.         XPK_OutBufLen (LONG)
  568.             The length of the output buffer you supply using XPK_OutBuf.
  569.             For decompression, must be decompressed size (see XpkExamine())
  570.             plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN.
  571.  
  572.         XPK_GetOutLen (LONG *)
  573.             Stores the total length of the (de)compressed data in the
  574.             variable pointed to by ti_Data.
  575.  
  576.         XPK_GetOutBufLen (LONG *)
  577.             Stores the length of the buffer allocated for the data in the
  578.             variable pointed to by ti_Data. FreeMem() the buffer you get
  579.             from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen.
  580.             Note: For the number of bytes written, refer to XPK_GetOutLen!
  581.  
  582.         XPK_OutMemType (LONG)
  583.             The type of memory to use for the output buffer.
  584.  
  585.     You have to specify different input and output streams always. So it
  586.     produces wrong results, when you supply same buffer for XPK_InBuf and
  587.     XPK_OutBuf or same filehandle for XPK_InFH and XPK_OutFH.
  588.     
  589.     PACKING TAGS
  590.  
  591.         XPK_PackMethod (STRPTR)
  592.             Use indicated method for packing. This would be a four
  593.             letter string of uppercase characters and numbers.
  594.  
  595.         XPK_PackMode (LONG)
  596.             Packing mode for sublib to use. Range is 0...100, where 100 is
  597.             most efficient.
  598.  
  599.         XPK_StepDown (BOOL)
  600.             Reduce packing efficiency to save mem if necessary.
  601.  
  602.         XPK_ChunkSize (LONG)
  603.             Chunk size to try to pack with. May be altered by the
  604.             master library.
  605.  
  606.     XPK_LossyOK (BOOL)
  607.         Some packers, like MPEG, reduce the file size by deleting some
  608.         information. These information cannot be restored. This tag
  609.         tells xpkmaster.library if it is ok for you, that some
  610.         information is deleted. It is FALSE by default. Use it with
  611.         care! Should be used only with sound or picture files.
  612.  
  613.     QUERY TAGS
  614.  
  615.         XPK_PackersQuery (struct XpkPackerList *)
  616.             Returns an array of available packers names in the XpkPackerList
  617.             structure whose address is stored in the ti_Data field of this
  618.             tag.
  619.  
  620.         XPK_PackerQuery (struct XpkPackerInfo *)
  621.             Returns information about one single packer in the XpkPackerInfo
  622.             structure whose address is stored in the ti_Data field of this
  623.             tag. See xpk/xpk.h for the meaning of the fields therein. You
  624.             must also supply XPK_PackMode.
  625.  
  626.         XPK_ModeQuery (struct XpkMode *)
  627.             Returns information about one single packer mode in the XpkMode
  628.             structure whose address is stored in the ti_Data field of this
  629.             tag. See xpk/xpk.h for the meaning of the fields therein. The
  630.             data of xm_Next field is illegal and must not be used. You
  631.             must also supply XPK_PackMethod and optionally XPK_PackMode,
  632.             otherwise the default mode will be used.
  633.  
  634.     OTHER TAGS
  635.  
  636.         XPK_GetError (STRPTR)
  637.             Write error msg to the buffer passed. The buffer must be of 
  638.             size XPKERRMSGSIZE. This tag calls XpkFault internally.
  639.             It is not recommended to use this tag any longer.
  640.  
  641.         XPK_Password (STRPTR)
  642.             Use password for en- or decoding. Passing a NULL pointer or
  643.             zero length string is equivalent to omitting this tag.
  644.  
  645.     XPK_Key16 (UWORD) (V4 REV25)
  646.         Supply a 16 bit key for decrunching of encrypted data. This
  647.         is only for decrunching of alien formats. XPK does not support
  648.         crunching with keys. Only know usage: crypted RNC files.
  649.  
  650.     XPK_Key32 (ULONG) (V4 REV25)
  651.         Supply a 32 bit key for decrunching of encrypted data. This
  652.         is only for decrunching of alien formats. XPK does not support
  653.         crunching with keys. Currently no know usage.
  654.  
  655.         XPK_ChunkHook (struct Hook *)
  656.             Hook function to call between chunks. Can print a progress
  657.             report, and if it returns a nonzero value, the (de)compression
  658.             will be aborted. See special chapter on chunk functions.
  659.  
  660.         XPK_PassThru (BOOL)
  661.             If true, data will just be handed trough on decompression if they
  662.             were not packed. Otherwise you get XPKERR_NOTPACKED.
  663.  
  664.         XPK_TaskPri (UBYTE)
  665.             The task priority to use during the (de)crunching. Use -1 for
  666.             background decompression.
  667.  
  668.         XPK_FileName (STRPTR)
  669.             The name to print in the progress report. If none is given, the
  670.             InName will be used when packing and the OutName when unpacking.
  671.  
  672.     PREFERENCES RELATED TAGS
  673.  
  674.         XPK_UseXfdMaster (BOOL) (V4)
  675.             If TRUE, xfdmaster.library will be used for checking unknown
  676.             files. Useable with XpkUnpack() and XpkExamine(). Is FALSE by
  677.             default, but depends on preference settings.
  678.  
  679.         XPK_UseExternals (BOOL) (V4)
  680.             If TRUE, xex libraries in LIBS:compressors/extern will be used
  681.             to check for crunched files. Useable with XpkUnpack() and
  682.             XpkExamine(). Default value is TRUE (depends on prefs!)
  683.  
  684.         XPK_PassRequest (BOOL) (V4)
  685.             If this is set a requester will be used to query the user for a
  686.             password, if none is given. Useable with XpkPack(). This is
  687.             disabled by default, but can be overridden using preferences
  688.             settings.
  689.  
  690.         XPK_Preferences (BOOL) (V4)
  691.             Tell xpkmaster.library whether to use its preferences system,
  692.             or not. This is enabled by default.
  693.  
  694.     XPK_ChunkReport (BOOL) (V4)
  695.         If this tag is set, xpkmaster.library brings an automatic chunk
  696.         report request (when the preferences semaphore has a valid
  697.         function for that). This is disabled by default.
  698.  
  699. xpkmaster.library/--progress--                 xpkmaster.library/--progress--
  700.  
  701.     THE PROGRESS REPORT HOOK
  702.         The progress report function is a standard hook function that will
  703.         be called after every chunk (de)compressed. This will be about 
  704.         every 30K, or just twice if the file format is not split in chunks.
  705.         If the field h_Entry in the hook is set, it will be called with 
  706.         the hook itself in A0 and the progress report structure in A1.
  707.         If the progress report function returns a nonzero value,
  708.         (de)compression aborts.
  709.         NOTE: Because hooks are not called in program environment, they
  710.         cannot be used in small data model of some compilers, as register
  711.         A4 is not passed through. So the hook either has to be compiled in
  712.         large data model or should use __saveds keyword of some compilers.
  713.  
  714. xpkmaster.library/--data hooks--             xpkmaster.library/--data hooks--
  715.  
  716.     GENERAL
  717.     You have four methods of passing data to xpkmaster.library: file-
  718.     names, filehandles, memory areas and hooks. The hooks are described
  719.     here. The hook field h_Entry has to be standard hook functions and
  720.     gets called with the hook itself in A0 and a pointer to a XpkIOMsg
  721.     in A1. Commands are stored in xiom_Type field, data in the other
  722.     fields. Return values are 0 or any of the XPKERR codes.
  723.     Commands XIO_FREE and XIO_ABORT may be ignored.
  724.  
  725.     Whenever an error occurs, you have to return an XPKERR code and
  726.     stop work. You get a XIO_ABORT call in this case later. When no
  727.     error occured, return 0.
  728.  
  729.     You may store private data in the free fields of XpkIOMsg structure.
  730.     You are always called with XIO_FREE or XIO_ABORT, so you can free
  731.     private stuff there. Buffers can be freed, when next time a buffer
  732.     allocation is required.
  733.  
  734.         NOTE: Because hooks are not called in program environment, they
  735.         cannot be used in small data model of some compilers, as register
  736.         A4 is not passed through. So the hook either has to be compiled in
  737.         large data model or should use __saveds keyword of some compilers.
  738.  
  739.     BUFFERS
  740.     Your hooks must be able to allocate buffers for read/write or pass
  741.     pointers to them, when they are already allocated. There are some
  742.     ways you have to handle this. First there is XIO_GETBUF. When getting
  743.     this command you have to pass a memory pointer pointing to a region
  744.     of at least xmm_Size size. For in hook there is another additionally
  745.     method. When XIO_READ is wanted and xiom_Ptr is zero, then you have
  746.     to pass (and allocate) a buf pointer and to fill it!
  747.     
  748.     The buffers must be valid until you are next time asked to allocate
  749.     a buffer (either with XIO_GETBUF or XIO_READ). Then you may return
  750.     old buffer pointer (when memory is large enough) or allocate a new
  751.     buffer and free the old buffer. When XIO_ABORT or XIO_FREE is send
  752.     all your buffers should be freed.
  753.  
  754.     NOTE: Your hooks do not get called only with your own buffers, but
  755.     also with xpkmaster internally buffers!
  756.  
  757.     When your input data is already in memory, you may pass pointers
  758.     to your memory regions and need not to allocate new memory for
  759.     XIO_READ when pointer is zero. When xiom_Ptr is not zero for
  760.     XIO_READ, you have to copy the data.
  761.  
  762.     Never expect, that you are called next time with buffer you
  763.     allocated. There may be write cycles of headers and other stuff
  764.     between XIO_GETBUF and XIO_WRITE. On reading it is equal.
  765.  
  766.     COMMANDS
  767.     XIO_READ    (in hooks only)
  768.       This command is called all time xpkmaster.library needs some data.
  769.       You have to fill the supplied memory area with input data of
  770.       needed size (not more!) When the input memory pointer is zero,
  771.       you have to allocate your own buffer and fill it. When you
  772.       allocated a buffer before (either by XIO_GETBUF or XIO_READ) you
  773.       can free it when pointer is zero.
  774.       Input:    xiom_Size    size of required data
  775.               xiom_Ptr    already allocated buffer or zero
  776.       Output:    xiom_Ptr    pointer to memory area of xiom_Size
  777.  
  778.     XIO_WRITE    (out hooks only)
  779.       This function is called, when some data was compressed and should
  780.       be stored now. Copy the contents of buffer to your data storing
  781.       system.
  782.       Input:    xiom_Size    size of data
  783.               xiom_Ptr    pointer to memory area of xiom_Size
  784.       Output:    none
  785.  
  786.     XIO_FREE    (both)
  787.       You get this when work is finished, free all your stuff now.
  788.       Input:    none
  789.       Output:    none
  790.  
  791.     XIO_ABORT    (both)
  792.       You get this when work was aborted, because an error occured.
  793.       Free all your stuff now.
  794.       Input:    none
  795.       Output:    none
  796.  
  797.     XIO_GETBUF    (both)
  798.       Asks you to pass a needed buffer. This buffer is not freed by
  799.       xpkmaster.library. Do this when getting XIO_FREE, XIO_ABORT or
  800.       the next XIO_GETBUF. Input buffers may be freed too, when
  801.       XIO_READ is called with no pointer.
  802.       Input:    xiom_Size    size of necessary buffer
  803.       Output:    xiom_Ptr    pointer to the buffer
  804.  
  805.     XIO_SEEK    (both)
  806.       Change the current position in your data (like dos.library Seek
  807.       command). When you are not able to handle seek, all better
  808.       functions will fail. Pass XPKERR_NOFUNC in this case as return
  809.       value. The offset you have to seek is always relative to current
  810.       position. It can be negative too. Return value (xiom_Size) is
  811.       same as for dos.library Seek command.
  812.       Input:    xiom_Size    offset you have to seek
  813.       Output:    xiom_Size    buffer position before seek
  814.  
  815.     XIO_TOTSIZE    (both)
  816.       You either have to tell the total input data size (in hook) or get
  817.       told the total output data size (out hook).
  818.  
  819.       OUT HOOK:
  820.       XIO_TOTSIZE may be ignored here. It tells you the maximum size
  821.       of output file (the real size may be shorter). This is for
  822.       example needed in memory hooks. This is only to inform you.
  823.       This command never needs to return an error code.
  824.       Input:    xiom_Size    total size of output data
  825.       Output:    none
  826.  
  827.       IN HOOK:
  828.       XIO_TOTSIZE cannot be ignored here. When your hook cannot
  829.       determine the total filesize, return any of the XPKERR values.
  830.       XIO_TOTSIZE is called only, when xpkmaster library really needs
  831.       filesize. Normal XPK files have size information in header and
  832.       XPK_InLen flags supplies information for input. In these cases
  833.       XIO_TOTSIZE is not used. But when returning an XPKERR, your hook
  834.       will not work in other cases, when size is required.
  835.       XIO_TOSIZE is used for following cases (when no XPK_InLen is
  836.       supplied!):
  837.       - decrunching of all non-xpk files
  838.       - crunching of files
  839.       NOTE: Only the size of the part, which should be processed, is
  840.       wanted. Most time this is from current position to end of file
  841.       (memory), but it may be shorter. But generally you have to
  842.       calculate size starting at current position.
  843.       Input:    none
  844.       Output:    xiom_Size    total size of input data
  845.  
  846.